Loading TOC...

GET /v1/values/{name}

Summary

Query the values in a lexicon or range index, or find co-occurrences of values in multiple range indexes. Optionally apply an aggregate function to the values or co-occurrences.

URL Parameters
q? A string query. For details, see Automatic Query Text Parsing and Grammar in the Search Developer's Guide and cts:query.
structuredQuery? A structured search query string. That is, a serialized representation of a search:query element. See Searching Using Structured Queries in the Search Developer's Guide.
options? The name of query options previously created via a PUT or POST request to the /v1/config/query service.
database? Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
view? The view of the query results to return in the response. Accepted values: values, aggregate, all. Default: all.
format? The type of the search results. This is equivalent to specifying the format in the Accept header. The format parameter overrides the Accept header if both are present. Accepted value: xml and json. Default: xml. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide.
collection* Filter results to include only matches in the named collection(s).
directory? Filter results to include only matches from documents in the specified database directory.
direction? The sort order of returned results. Accepted values: ascending or descending. The default direction depends on the sort order defined in the options. The default is ascending for item-order and descending for frequency-order.
frequency? The method of calculating frequency. Accepted values: item (default) or fragment. Fragment frequency returns the number of fragments with an included value. Item frequency returns the total number occurrences of an included value.
limit? The maximum number of values or tuples to retrieve from the lexicon. Default: No limit.
start? The index of the first result to return from the subset defined by limit. Results are numbered beginning with 1. Default: 1.
pageLength? The number of values to return within the subset of values defined by limit, beginning with the value selected by start. Default: Return all selected values.
aggregate? The name of a built-in or user-defined aggregate function to run against the lexicon. If the function is not a built-in aggregate, you must also supply aggregatePath. The supported builtin aggregate functions are: sum, avg, min, max, median, count, stddev, stddev-population, correlation, covariance, covariance-population, variance, variance-population.
aggregatePath? The path to the native plugin library containing the implementation of the function named by the aggregate function. If the path is empty or is not specified, a built-in aggregate is assumed.
transform? Names a search result transformation previously installed via the /transforms service. The transformation is applied to the <search:response/> after applying user-defined transforms defined in the query options using <transform-results>. For details, see Transforming the Search Response in the REST Application Developer's Guide.
trans:{name}* A transform parameter name and value. For example, trans:myparam=1. Transform parameters are passed to the transform named in the transform parameter.
txid? The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
Request Headers
Accept* The expected MIME type of the information in the response. Accepted types: application/json or application/xml. Ignored if the request includes a format parameter value.
Response Headers
Content-type The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Response

On success, MarkLogic Server responds with a 200 status and the query results in the response body.

If you use an aggregate function and the target lexicon type does not support the chosen operation, such as stddev on a string valued lexicon, or if the aggregate function does not exist, MarkLogic Server responds with a 400 (Bad Request) status, with additional error information in the response body.

Required Privileges

This operation requires the rest-reader role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-reader

Usage Notes

Query options named in the options request parameter must be pre-installed using the /config/query service. If no query options are specified, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options. To configure query options, use the /config/query service.

When you apply a builtin or user defined aggregate function, the output is dependent on the function. For details, see Analyzing Lexicons and Range Indexes With Aggregate Functions in the REST Application Developer's Guide.

For more details, see Querying Lexicons and Range Indexes in the REST Application Developer's Guide.

Example

Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ curl --anyauth --user user:password -X GET \
    http://localhost:8000/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, as XML.

<values-response name="speaker" type="xs:string" \
    xmlns="http://marklogic.com/appservices/search" \
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <distinct-value frequency="1">[GOWER]</distinct-value>
  <distinct-value frequency="1">[PROSPERO]</distinct-value>
  ...
</values-response>

Example

Assume the following query options are installed with the name "index-options":

{
  "options": {
    "values": [
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": { "ns": "", "name": "SPEAKER" }
        }
      }
    ]
  }
}

$ curl --anyauth --user user:password -X GET \
    http://localhost:8000/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, as JSON.
{
  "values-response": {
    "name": "speaker",
    "type": "xs:string",
    "distinct-value": [
      {
        "frequency": 1,
        "_value": "[GOWER]"
      },
      {
        "frequency": 1,
        "_value": "[PROSPERO]"
      },
      ...
    ],
    "metrics": {
      "values-resolution-time": "PT0.016665S",
      "aggregate-resolution-time": "PT0.00001S",
      "total-time": "PT0.018102S"
    }
  }
}

Example

Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ curl --anyauth --user user:password -X GET \
    'http://localhost:8000/v1/values/speaker?options=index-options&limit=10&start=4&pageLength=3'

==> The 4th through the 6th distinct values of the SPEAKER element in 
    element range index, as XML.

<values-response name="speaker" type="xs:string" \
    xmlns="http://marklogic.com/appservices/search" \
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <distinct-value frequency="1">A Lord</distinct-value>
  <distinct-value frequency="2">A Patrician</distinct-value>
  <distinct-value frequency="1">A Player</distinct-value>
  <metrics>
    <values-resolution-time>PT0.000258S</values-resolution-time>
    <total-time>PT0.002038S</total-time>
  </metrics>
</values-response>

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.